Node / meshtastic / Meshtastic-Android / files / .github / copilot-instructions.md

Displaying Raw • View rendered • Download

Tc9d1d9# Meshtastic Android — Copilot Instructions

Tff7b72> **Full rules**: `AGENTS.md` is the source of truth. This file is a compact quick-reference for build commands and task naming. For architecture, conventions, and workflow details, consult `AGENTS.md` and the `.skills/` playbooks listed at the bottom.

Tc9d1d9## Build, Test & Lint

**Requires:** JDK 21, Ta5d6ff`ANDROID_HOME` set, proto submodule initialized.

Ta5d6ff```Ta5d6ffbash

T8b949e# Bootstrap (run once per fresh clone)

git submodule update --init

Tff7b72[ -f local.properties Tff7b72] Tff7b72|| cp secrets.defaults.properties local.properties

T8b949e# Full local verification (formatting → lint → compile → tests)

./gradlew spotlessApply detekt assembleDebug Tffa657test allTests

T8b949e# Single module tests (KMP module)

./gradlew :core:data:allTests

T8b949e# Single module tests (Android-only module like :app)

./gradlew :androidApp:testFdroidDebugUnitTest

T8b949e# Cross-platform compilation check (no tests)

./gradlew kmpSmokeCompile

T8b949e# Flavor-specific lint

./gradlew lintFdroidDebug lintGoogleDebug

Ta5d6ff```

Tff7b72> Both `test` AND `allTests` are needed. `allTests` covers KMP modules; `test` covers pure-Android modules. Neither alone catches everything.

Tc9d1d9### Gradle task naming (KMP vs Android-only)

KMP modules have different task names than pure-Android modules. Using the wrong name silently skips tests or fails resolution.

| Intent | KMP modules (Ta5d6ff`core:*`, Ta5d6ff`feature:*`) | Android-only (Ta5d6ff`app`, Ta5d6ff`core:api`, Ta5d6ff`core:barcode`) |

|--------|--------------------------------------|--------------------------------------------------|

| Run tests | Ta5d6ff`:module:allTests` | Ta5d6ff`:module:testFdroidDebugUnitTest` |

| Detekt | Ta5d6ff`:module:detekt` (lifecycle task) | Ta5d6ff`:module:detekt` |

| Compile check | Ta5d6ff`:module:compileKotlinJvm` | Ta5d6ff`:module:compileFdroidDebugKotlin` |

**Common mistakes:**

Tff7b72- ❌ Ta5d6ff`:core:network:detektMain` — does not exist in KMP; variants are Ta5d6ff`detektJvmMain`, Ta5d6ff`detektMetadataCommonMain`, etc. Use Ta5d6ff`:core:network:detekt` instead.

Tff7b72- ❌ Ta5d6ff`:feature:connections:testDebugUnitTest` — ambiguous in KMP modules. Use Ta5d6ff`:feature:connections:allTests`.

Tff7b72- ❌ Ta5d6ff`:feature:connections:compileFdroidDebugKotlin` — wrong for KMP. Use Ta5d6ff`:feature:connections:compileKotlinJvm` or Ta5d6ff`kmpSmokeCompile`.

Tc9d1d9## Quick Reference

Tff7b72- **Architecture**: KMP project (Android, Desktop, iOS). Business logic in Ta5d6ff`commonMain`; platform shells (Ta5d6ff`androidApp/`, Ta5d6ff`desktopApp/`) wire DI and host UI. See Ta5d6ff`AGENTS.md` and Ta5d6ff`.skills/kmp-architecture/`.

Tff7b72- **Flavors**: Ta5d6ff`fdroid` (OSS) / Ta5d6ff`google` (Maps + DataDog). Only one installable at a time (different signing keys).

Tff7b72- **Verify before push**: Run Ta5d6ff`./gradlew spotlessApply detekt assembleDebug test allTests`, then confirm CI with Ta5d6ff`gh pr checks <PR>`.

Tff7b72- **Strings**: Ta5d6ff`stringResource(Res.string.key)` — run Ta5d6ff`python3 scripts/sort-strings.py` after adding strings.

Tff7b72- **Icons**: Ta5d6ff`MeshtasticIcons` (from Ta5d6ff`core/ui/icon/`), not Ta5d6ff`material.icons.Icons`.

Tff7b72- **Error handling**: Ta5d6ff`safeCatching {}` (not Ta5d6ff`runCatching {}`) in coroutine code.

Tff7b72- **Dispatchers**: Ta5d6ff`org.meshtastic.core.common.util.ioDispatcher`, not Ta5d6ff`Dispatchers.IO`.

Tff7b72- **Navigation**: Ta5d6ff`MeshtasticNavDisplay` + Ta5d6ff`NavigationBackHandler` (not Android Ta5d6ff`BackHandler`).

Tff7b72- **Protos**: Ta5d6ff`core/proto/` is a read-only git submodule. Never modify proto files.

Tff7b72- **Branches**: Must start with Ta5d6ff`feat/`, Ta5d6ff`fix/`, Ta5d6ff`chore/`, Ta5d6ff`docs/`, Ta5d6ff`build/`, Ta5d6ff`ci/`, Ta5d6ff`refactor/`, Ta5d6ff`test/`, Ta5d6ff`deps/`, or a numeric spec prefix. Always branch off Ta5d6ff`origin/main`.

<!-- SPECKIT START -->

Tc9d1d9## Active Plan

Tff7b72- **Feature**: Reorder Bottom Navigation Tab Labels

Tff7b72- **Plan**: Ta5d6ff`specs/20260520-153412-nav-tab-labels/plan.md`

Tff7b72- **Branch**: Ta5d6ff`jamesarich/issue-5543-alignment-reorder-bottom-navigation-tab-91d55d`

<!-- SPECKIT END -->

Tc9d1d9## Deeper Guidance

Consult Ta5d6ff`.skills/` for detailed playbooks:

Tff7b72- Ta5d6ff`.skills/project-overview/` — Full codebase map and bootstrap

Tff7b72- Ta5d6ff`.skills/kmp-architecture/` — Source-set rules, expect/actual

Tff7b72- Ta5d6ff`.skills/compose-ui/` — Adaptive UI, string resources

Tff7b72- Ta5d6ff`.skills/navigation-and-di/` — Nav 3 & Koin patterns

Tff7b72- Ta5d6ff`.skills/testing-ci/` — CI architecture, verification matrix

Tff7b72- Ta5d6ff`.skills/implement-feature/` — Feature development workflow

Tff7b72- Ta5d6ff`.skills/code-review/` — PR hygiene checklist

Tff7b72- Ta5d6ff`.skills/speckit/` — Spec Kit SDD workflow, slash commands, constitution